<!-- $Id: using-advanced-help.html,v 1.6 2008/10/17 18:55:38 merlinofchaos Exp $ -->
<p>The <em>Advanced help</em> system is a pluggable system that provides advanced help facilities for Drupal and its modules. Although the advanced help does not provide general help by itself, it provides a powerful and easy framework that modules may use to provide their own help.
</p>

<p>
Modules utilizing <em>Advanced help</em> should create a 'help' subdirectory inside their
module's directory. Place the file MODULENAME.help.ini in this subdirectory, formatted
similar to the following example:
</p>
<pre>
[buses]
title = "How buses are tied into the system"
file = buses

[TOPIC_ID]
title = "Title of topic".
file = filename of topic, without the .html extension.
weight = How important the topic is on the index page.
parent = The optional topic parent to use in the breadcrumb, 
         either topic or module%topic.
</pre>

<p>
All topics are addressed by the module providing the topic, and by the topic
id. To embed links, use the following format:
</p>
<code>
$output .= theme('advanced_help_topic', $module, $topic);
</code>

<p>Inside your help file, link to other topics using the format <strong>&lt;a href="&amp;topic:module/topic&amp;"&gt;</strong>. This
format will ensure the popup status remains consistent when switching between links.</p>

<p>Use <strong>&lt;a href="&amp;path&amp;example.jpg"&gt;</strong> to reference items
within the help directory, such as images you wish to embed within the help text.</p>

<p>Use <strong>&lt;a href="&amp;base_url&amp;admin/settings/site-configuration"&gt;</strong> to reference any normal path in the site.</p>

<p>If the search module is enabled, the contents of help system will be indexed on cron. If you enable new modules and wish to immediately index its help text, visit the "Administration -> Reports -> Status report" and click the "Run cron manually" link.</p>

<p>Example: <a href="&path&nowhere.jpg">Don't click this!</a></p>

<p>See: <a href="&topic:advanced_help/ini-file&">ini file format</a></p>

<p><strong>NOTE: </strong> In previous versions Advanced Help did not require the &amp;'s wrapped around the topic:, path:, and base_url: links.  This
is currently still supported, but may be removed in a future version.  By adding the &'s these tokens are now not limited to href="" and src="" paramaters.</p>
